Skip to content

feat: safe keycard regeneration SDK support (WCN-3922) - #10145

Merged
davidkaplanbitgo merged 1 commit into
masterfrom
yashaanand/wcn-3922-safe-keycard-methods
Nov 13, 2026
Merged

davidkaplanbitgo merged 1 commit into
masterfrom
yashaanand/wcn-3922-safe-keycard-methods

Conversation

@yashaanand

@yashaanand yashaanand commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Client-side SDK support for Safe keycard regeneration (WCN-3922, M2 of the Safe Keycard Regeneration TDD). Four module areas:

  • sdk-lib-mpc — pure CBOR reduce helpers reduceDklsKeyShare / reduceMpsKeyShare extracted from the DKG classes, pinned by golden fixtures whose reduced bytes were produced by master's pre-extraction getReducedKeyShare (DKLS: the existing userShare/backupShare fixtures; MPS: a share captured from a live DKG session), so the goldens are independent of the new helpers.
  • sdk-lib-safes — parseSafeKeycardBox accepts any non-empty declared subset of root slots; unknown keys, non-string/entry values, and empty slot sets are rejected; canonical key order preserved. Ports validateJSONAgainstCodec from the unmerged WCN-2734 branch, adapted to master's {prv, chainCode} ed25519 entry union.
  • key-card — safe keycard generation accepts a slot subset (generateSafeQrData, buildSafeBoxData) and gains a blob-returning variant generateSafeKeycardBlob for mobile; both share one draw path, and the saving generateSafeKeycard behaves as before.
  • sdk-core — Safe.requestKeycardAccess / Safe.claimKeycardMaterial (WCN-3921 route contract, decoded minimally with passthrough records), buildSafeKeycardRoots (user envelopes re-encrypted under the creation password in one shared KDF session, multisig backup envelopes byte-identical, MPC roots reduced + re-wrapped into the ceremony-shaped reducedEncryptedPrv), decryptSafeKeycardBoxD, generateSafe takes passcodeEncryptionCode (stored as originalPasscodeEncryptionCode on the multisig and MPC user/backup roots) and returns the root triplets, and decryptSafeKeycard / deriveSafeWalletKeys tolerate slot subsets with named missing-root errors.

Verification

  • @bitgo/sdk-lib-mpc: 275 passing, incl. fixed-byte goldens for DKLS + MPS reduce.
  • @bitgo/sdk-lib-safes: 96 passing (subset codec + validateJSONAgainstCodec coverage).
  • @bitgo/key-card: 45 passing (incl. the blob variant for a slot subset with Box D). Includes end-to-end tests (safeKeycardRegen.ts) that run the real Safes.generateSafe and Safe.claimKeycardMaterial against WP mocks in the WCN-3920 (backup envelope redacted on key add) and WCN-3921 (claim projection {id,type,source,pub?,commonKeychain?,encryptedPrv?} + passcodeEncryptionCode) wire shapes, then buildSafeKeycardRoots → generateSafeQrData → parseSafeKeycardBox → decryptSafeKeycard → deriveSafeWalletKeys, with real sdk-api encryption and real multisig/ed25519/DKLS/MPS root material:
    • creation-time keycard straight from the generateSafe triplets: all 4 roots + Box D; originalPasscodeEncryptionCode threaded to every multisig and MPC user/backup registration; no plaintext backup prv returned.
    • regeneration after a password change via the Box D path (creation password recovered from the original Box D + claimed code, not typed), for all 4 roots and for a 2-slot subset: every box opens with the creation password and not the changed one, multisig backups byte-identical, new Box D decrypts to the creation password.
  • @bitgo/sdk-core safe + keychain suites: 202 passing (buildSafeKeycardRoots same-password/password-change/wrong-password/missing-envelope cases, 2-slot round-trip through parseSafeKeycardBox → decryptSafeKeycard → deriveSafeWalletKeys, Box D decrypt, claim mapping, generateSafe triplet return + passcodeEncryptionCode threading, rotation skip for envelope-less backup roots).
  • @bitgo/sdk-coin-algo safe recovery (consumer of the widened deriveSafeWalletKeys): 242 passing.
  • @bitgo/express: 1991 passing (full suite, BITGOJS_TEST_PASSWORD set).
  • Full monorepo TypeScript build (yarn at root): all packages compile clean.
  • Lint: 0 errors on all changed files (pre-commit lint-staged + direct eslint). yarn lint-changed additionally fails in @bitgo/passkey-crypto, which is byte-identical to master with 1798 pre-existing prettier errors — unrelated.
  • Ticket acceptance proofs observed in test output: golden reduce byte equality (DKLS + MPS), 2-slot subset round-trip, password-change keycard opened with the creation password, Box D decrypt returning the creation password, rotation test showing the backup root emits no bulk update.

Breaking changes

  • ISafes.generateSafe now returns SafeCreationResult ({ safe, rootKeychains }) and createSafeKeys returns SafeKeys & { rootKeychains } — the root triplets (incl. reducedEncryptedPrv) the keycard needs. This @experimental surface's only caller is retail's createSafeWithSdk, bumped in M3 (WCN-3923). Express handlers keep their documented wire contracts (safes.generate returns SafeData; keys/generate returns only root key ids — no key material over the wire).
  • decryptSafeKeycard returns Partial<DecryptedSafeRoots>; full records remain assignable, and deriveSafeWalletKeys throws a named error for absent slots.

Coordination & scope notes

  • WCN-2734: the subset codec commit 031757ec9d is unmerged on recovery/WCN-2734 and predates master's Ed25519ChainCodeEntry; this PR ports its approach adapted to current master (union entry codec kept). If WCN-2734 merges first, rebase and prefer this superset version.
  • Size: +1897 / −174. The full-4 end-to-end test was added back so every WCN-3922 test requirement is covered; it supersedes the overlapping sdk-core unit round-trip and password-change test, which were removed, and the goldens are inlined single-line hex.
  • Cross-checked against WCN-3921 (bitgo-microservices #64270 @ 364acd4): request 200/202/409 bodies and the claim projection match the SDK codecs; both routes need a login session unlocked with OTP (no access tokens), now documented on the SDK methods. key-card gains @bitgo/sdk-lib-mpc and @bitgo/utxo-lib as devDependencies for the end-to-end test.
  • Beta publish: the October publish failures (E403 republish conflicts, tracked in fix(scripts): reconcile publish conflicts and wait for visibility (SI-2040) #9997) were resolved by fix(scripts): make beta publish conflict-tolerant and registry-truth #10076; Publish @bitgo-beta runs on master have succeeded since. The beta ships with the first publish after this merges, then the bitgo-ui and retail bumps (WCN-3923).
  • No client-side runtime flag: the methods are additive on an @experimental surface and the WP routes are gated server-side by wp_safe_keycard_access (WCN-3919/3921); subset/blob keycard generation is pure client-side formatting.

Ticket: WCN-3922

@linear-code

linear-code Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

WCN-3922

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

⚠️ Compatibility checks are failing on Node.js 27-nightly (experimental, non-blocking). This does not block merge, but it signals an incompatibility to fix before this release becomes supported.

View run

@yashaanand
yashaanand force-pushed the yashaanand/wcn-3922-safe-keycard-methods branch from e5bcfaa to 9b3dbe8 Compare November 9, 2026 19:58
claude[bot]

This comment was marked as outdated.

@yashaanand
yashaanand force-pushed the yashaanand/wcn-3922-safe-keycard-methods branch from 9b3dbe8 to 72dba15 Compare November 9, 2026 21:50
claude[bot]

This comment was marked as outdated.

@yashaanand

Copy link
Copy Markdown
Contributor Author

@claude review

@yashaanand
yashaanand force-pushed the yashaanand/wcn-3922-safe-keycard-methods branch from 72dba15 to 4711c59 Compare November 11, 2026 16:30
claude[bot]

This comment was marked as outdated.

@yashaanand
yashaanand force-pushed the yashaanand/wcn-3922-safe-keycard-methods branch 3 times, most recently from dc7823a to 6825576 Compare November 11, 2026 18:45
@yashaanand

Copy link
Copy Markdown
Contributor Author

@claude review

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I re-reviewed the latest push and found no new bugs. My two earlier points look addressed in the code. Because this is a large change to key-handling code in CODEOWNER-owned modules, a human review is still worth doing.

What was reviewed:

  • buildSafeKeycardRoots (keycard.ts): MPC backups that already have reducedEncryptedPrv are now checked against the creation password and copied unchanged. A backup that only opens with the current password now throws SafeKeycardBackupsOnCurrentPasswordError instead of a generic wrong-password error. The shared encryption session is destroyed in finally.
  • generateSafeQrData (key-card): the empty-roots guard now counts only slots that are actually defined, so a map like { ecdsaMpc: undefined } is rejected.
Extended reasoning...

The change adds Safe keycard regeneration across sdk-core, sdk-lib-mpc, sdk-lib-safes, key-card and express (31 files, about +1900/-170). That includes re-encrypting private keys, reducing MPC key shares, and a breaking change to the return shape of generateSafe. It handles key material and passwords directly, and sdk-core, sdk-lib-mpc and key-card have CODEOWNERS (wallet-core, hsm). The new commit plausibly fixes both earlier inline findings, but the author resolved one of those threads and this bot resolved the other, so no independent reviewer has signed off. That is why I'm deferring instead of approving.

@yashaanand
yashaanand marked this pull request as ready for review November 11, 2026 19:19
@yashaanand
yashaanand requested review from a team as code owners November 11, 2026 19:19

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

Tip: disable this comment in your organization's Code Review settings.

@davidkaplanbitgo davidkaplanbitgo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nits only

Comment thread modules/key-card/src/generateQrData.ts Resolved
s84krish
s84krish previously approved these changes Nov 11, 2026

@s84krish s84krish left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm! non-blocking comment

Comment thread modules/sdk-core/src/bitgo/safe/safe.ts Resolved
Comment thread modules/sdk-core/src/bitgo/safe/safe.ts Resolved
sdk-lib-mpc: pure CBOR reduce helpers (reduceDklsKeyShare, reduceMpsKeyShare) extracted from
the DKG classes, pinned by golden fixtures whose reduced bytes were produced by master's
pre-extraction Dkg.getReducedKeyShare. sdk-lib-safes: parseSafeKeycardBox accepts any non-empty
declared subset of root slots (aligned with the unmerged WCN-2734 branch, adapted for the
ed25519 chain-code entry). key-card: safe keycard generation accepts a slot subset and gains a
blob-returning variant (generateSafeKeycardBlob) for mobile, sharing one draw path with
generateSafeKeycard. sdk-core: Safe.requestKeycardAccess / claimKeycardMaterial (WCN-3921 route
contract), buildSafeKeycardRoots (Box A re-encrypt under the creation password, MPC reduce +
re-envelope in one encryption session, backup envelopes byte-identical), Box D decrypt helper,
generateSafe takes passcodeEncryptionCode (stored as originalPasscodeEncryptionCode on the
multisig and MPC user/backup roots) and returns the root triplets incl. reducedEncryptedPrv,
decrypt/derive tolerate slot subsets. Express handlers keep their documented wire contracts
(root key ids only; no key material over the wire).

End-to-end key-card tests drive the real Safes.generateSafe and Safe.claimKeycardMaterial
against WP mocks in the WCN-3920 (redacted backup on key add) and WCN-3921 (claim projection)
wire shapes, then generate, parse, decrypt and derive all 4 roots and a 2-slot subset with real
encryption: the creation-time keycard from the returned triplets, and a post-password-change
regeneration that takes the creation password from Box D. These supersede the overlapping
sdk-core unit round-trip.

Experimental/beta surface; no runtime flag — the routes are gated server-side by
wp_safe_keycard_access.

Ticket: WCN-3922
@yashaanand
yashaanand dismissed stale reviews from davidkaplanbitgo and s84krish via 542c765 November 12, 2026 16:22
@yashaanand
yashaanand force-pushed the yashaanand/wcn-3922-safe-keycard-methods branch from 6825576 to 542c765 Compare November 12, 2026 16:22
@yashaanand

Copy link
Copy Markdown
Contributor Author

@claude were the previous review points addressed? any blockers?

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @yashaanand's task in 35s —— View job


Review follow-up: previous points

All earlier review points are addressed in the code I read. I found no blockers. I read the code and did not run the tests or build.

Addressed (checked in the current tree)

  • MPC backup with only reducedEncryptedPrv: buildSafeKeycardRoots now copies it after a trial decrypt, and reduces from encryptedPrv only when there is no reduced envelope (keycard.ts ~L169-183). It throws a named error if both are missing.
  • Backups rotated to the current password: this now throws SafeKeycardBackupsOnCurrentPasswordError (a subclass of IncorrectPasswordError) instead of a misleading wrong-password error.
  • Empty-box keycard: generateSafeQrData now counts defined slots, so { ecdsaMpc: undefined } is rejected. The reason for skipping absent slots is commented in buildSafeBoxData (a root type can be disabled for a safe).
  • any in validateJSONAgainstCodec: it now uses Record<string, unknown> and t.Type<A, unknown, unknown>.
  • null slot silently dropped: buildSafeKeycardRoots now validates every slot first. It throws on an unknown slot and on a non-triplet value (via isTriplet).
  • Double casts in claimKeycardMaterial: removed. The claim is decoded against a projection codec, and triplet.user/backup/bitgo are assigned directly.
  • Single-slot refactor: the work is now split into SafeKeycardRootBuilder.buildMultisigSlot and buildMpcSlot, with a thin loop in buildSafeKeycardRoots.
  • commonKeychain validation:
    • reduceMpsKeyShare asserts /^[0-9a-f]{128}$/i.
    • reduceDklsKeyShare checks the decoded shape and byte lengths through assertReducedKeyShareShape.
    • keycard.ts:159 collects the present commonKeychain values from the triplet. I did not read the consistency check that consumes them, so I can't say whether it enforces that they agree.

Open items

  • None blocking. As the earlier bot reviews said, this is crypto-sensitive key-handling code in CODEOWNER modules, so it still needs a human approval.
  • For merge, you still need green CI. The Node 27-nightly failure is marked non-blocking.
  • The WCN-2734 rebase note in the PR description still applies if that branch merges first.

@davidkaplanbitgo
davidkaplanbitgo merged commit 76020a5 into master Nov 13, 2026
27 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants